---
sidebar_position: 6
description: Derive Hasura Actions
keywords:
  - hasura
  - docs
  - actions
  - derive
sidebar_label: Derive Actions
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';

# Derive Actions

## Introduction

It is a typical requirement to run some custom business logic before actually executing a mutation / query, for example,
to perform validations or to enrich some data from an external source. Actions can be used to achieve this.

To help with creation of such actions, Hasura lets you derive an action from an existing query or mutation by:

- Auto-generating the GraphQL types defining the action
- Generating the handler code to delegate the action back to the original query or mutation after executing some
  business logic

## Generate derived action GraphQL types

Hasura can generate the relevant GraphQL types required to define an action given a GraphQL operation.

For example, let's say we would like to derive an action from the mutation:

```graphql
mutation insertAuthor {
  insert_author_one(object: { name: "Some name" }) {
    id
    name
  }
}
```

As the derived action will need to accept some arguments, we can convert the above mutation to use variables instead
which can then become arguments to our derived action.

```graphql
mutation insertAuthor($name: String) {
  insert_author_one(object: { name: $name }) {
    id
    name
  }
}
```

Now that we have a mutation with arguments being accepted as variables, we can derive our action:

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

Head to the `API` tab of the Console and paste / generate your query in the GraphiQL window.

Next hit the `Derive action` button as shown below:

<Thumbnail src="/img/actions/actions-derive-button.png" alt="Console derive action button" />

This will redirect you to the `Add a new action` page with the Action definition auto-filled.

<Thumbnail src="/img/actions/actions-derive-types.png" alt="Console derived action types" />

</TabItem>
<TabItem value="cli" label="CLI">

To create the derived action, run:

```bash
hasura actions create insertAuthor --derive-from 'mutation insertAuthor($name: String) {
     insert_author_one(
       object: {
         name: $name
     }) {
     id
     name
   }
 }'
```

This will open up an editor with `metadata/actions.graphql` with the following action types auto filled.

```graphql
type Mutation {
  insertAuthor(name: String): InsertAuthorOutput
}

type InsertAuthorOutput {
  id: Int!
  name: String!
}
```

:::info Note

The action name will be picked up from the argument of the command and not the mutation string.

:::

</TabItem>

</Tabs>

:::info Note

- The derived output type will be derived from the actual output type of the original query or mutation and not the
  selection-set of the given query or mutation string.
- As currently custom object types can only have scalar / enum fields any object type fields in the original output type
  will be dropped in the derived output type.

:::

## Generate handler code for a derived action

For a derived action, Hasura can generate the relevant handler code to delegate the action back to the original
operation.

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

Head to the `Actions -> [action-name] -> Codegen` tab in the Console

You can select the framework of your choice to get the corresponding handler boilerplate code.

<Thumbnail src="/img/actions/actions-derive-codegen.png" alt="Console derived action codegen" />

:::info Note

The information about derived Actions are stored locally on the browser and hence it is currently only possible to
generate the delegation code from the browser where the action was created.

:::

</TabItem>
<TabItem value="cli" label="CLI">

You will have to set up codegen in the CLI first to do this as explained in
[Generating handler code for your action](/actions/codegen/index.mdx#actions-codegen-execute)

After saving the GraphQL types generated by the `actions create` command in the previous section, the CLI will prompt you
if you would like to generate the corresponding codegen files. Hit <em>y</em> to generate the codegen files with the
delegation logic.

The CLI does not persist information about derived Actions. Hence if you wish to generate the delegation code, you might
want to pass the query or mutation string while running the codegen command:

```bash
hasura actions codegen <action-name> --derive-from '<query/mutation string>'
```

</TabItem>
</Tabs>

## Hiding the original mutation in the API

Once a mutation is derived, you might want to hide it from your public GraphQL API but still want to use it from your
action handler.

To achieve this you can mark the mutation as `backend_only` so that it can be accessed only via "trusted sources". See
[Backend only](/auth/authorization/permissions/backend-only.mdx) for more details

Setting `backend-only` is currently available for insert, update and delete mutations.

:::info Additional Resources

Introduction to Hasura Actions -
[View Recording](https://hasura.io/events/webinar/hasura-actions/?pg=docs&plcmt=body&cta=view-recording&tech=).

:::
